<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Running Stories</title>
</head>

<body>

<h2>Running Stories</h2>

<p>JBehave is designed to be embedded in different development
environments. The JBehave Core module contains support for running
stories as JUnit tests - which can be run either in your favourite IDE
or in your command-line build that supports JUnit tests. Other unit
testing frameworks, e.g. TestNG or Spring Test, can also be used very
easily, c.f. <a href="faq.html">FAQ</a>.</p>

<p>You can also run stories using the JBehave <a
	href="ant-tasks.html">Ant tasks</a> or <a href="maven-goals.html">Maven
goals</a>, which provide a facade around the Embedder functionality.</p>
<p>JBehave provides the <a
	href="javadoc/core/org/jbehave/core/embedder/Embedder.html">Embedder</a>
as the core entry point to running stories. The Embedder can be
configured in multiple way, c.f. the <a href="configuration.html">configuration</a>.</p>

<h2>Multiple running modes</h2>

<p>Stories can be run in different modes:</p>

<ul>
	<li>as embeddables: An <a
		href="javadoc/core/org/jbehave/core/Embeddable.html">Embeddable</a> is
	an abstraction of a running mode, which can run a single story, e.g. if
	extending <a href="javadoc/core/org/jbehave/core/junit/JUnitStory.html">JUnitStory</a>
	or can run multiple stories, e.g. if extending <a
		href="javadoc/core/org/jbehave/core/junit/JUnitStories.html">JUnitStories</a>.
	The Embeddable instances allow their <a href="configuration.html">configuration</a>.
	</li>
	<li>as paths: once we have specified an instance of an <a
		href="javadoc/core/org/jbehave/core/embedder/Embedder.html">Embedder</a>,
	with its configuration, we run stories specified by paths.</li>
	<li>with annotated embedder runner: an <a
		href="javadoc/core/org/jbehave/core/junit/AnnotatedEmbedderRunner.html">AnnotatedEmbedderRunner</a>
	is an implementation of the JUnit Runner, which allows annotated
	specification of the Embedder to be used to run the stories. C.f. <a
		href="configuration.html">configuration</a> on how to use
	annotatations to configure the Embedder.</li>
    <li>with annotated path runner: an <a
        href="javadoc/core/org/jbehave/core/junit/AnnotatedPathRunner.html">AnnotatedPathRunner</a>
    is an extension of AnnotatedEmbedderRunner which creates a JUnit suite containing each story path
    and resolving the path to a human readable form that plays nicely with any IDE that provides 
    JUnit integration.</li>

</ul>

<h2>Running Stories in a framework-neutral way</h2>

<p>The Embedder can also be used to run the stories in any IDE
environment, without the need to extend any base class. In the following
example we use JUnit annotatation to denote different running instances:
</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
public class TraderStoryRunner {

	@Test
	public void runClasspathLoadedStoriesAsJUnit() {
		// Embedder defines the configuration and candidate steps
		Embedder embedder = new TraderEmbedder();
        List<String> storyPaths = ... // use StoryFinder to look up paths
		embedder.runStoriesAsPaths(storyPaths);
	}

	@Test
	public void runURLLoadedStoriesAsJUnit() {
		// Embedder defines the configuration and candidate steps
		Embedder embedder = new URLTraderEmbedder();
        List<String> storyPaths = ... // use StoryFinder to look up paths
        embedder.runStoriesAsPaths(storyPaths);
	}

}
]]>
</script>

<p>where the TraderEmbedder/URLTraderEmbedder define the
configuration using the loading from the classpath and URL resources,
respectively. E.g.:</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
public class TraderEmbedder extends Embedder {

    @Override
    public EmbedderControls embedderControls() {
        return new EmbedderControls().doIgnoreFailureInStories(true).doIgnoreFailureInView(true);
    }

    @Override
    public Configuration configuration() {
        Class<? extends TraderEmbedder> embedderClass = this.getClass();
        return new MostUsefulConfiguration()
            .useStoryLoader(new LoadFromClasspath(embedderClass.getClassLoader()))
            .useStoryReporterBuilder(new StoryReporterBuilder()
                .withCodeLocation(CodeLocations.codeLocationFromClass(embedderClass))
                .withDefaultFormats()
                .withFormats(CONSOLE, TXT, HTML, XML)
                .withCrossReference(new CrossReference()))
            .useParameterConverters(new ParameterConverters()
                    .addConverters(new DateConverter(new SimpleDateFormat("yyyy-MM-dd")))) // use custom date pattern
            .useStepPatternParser(new RegexPrefixCapturingPatternParser(
                            "%")) // use '%' instead of '$' to identify parameters
            .useStepMonitor(new SilentStepMonitor());                               
    }

    @Override
    public InjectableStepsFactory stepsFactory() {
        return new InstanceStepsFactory(configuration(), new TraderSteps(new TradingService()), new BeforeAfterSteps());
    }

}
]]>
</script>

<h2>Running Remote Stories</h2>

<p>JBehave supports running both local and remote stories. To run
remote stories, we need to use a URL-based loader with an appropriate
remote code location.  The difference w.r.t. the local run is minimal:</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
public class RemoteTraderStories extends TraderStories {

    @Override
    public Configuration configuration() {
        return super.configuration()
               .useStoryLoader(new LoadFromURL())
               .useStoryReporterBuilder(
                       new StoryReporterBuilder()
                           .withCodeLocation(codeLocationFromURL("http://jbehave.org/reference/examples/stories/"))
                           .withDefaultFormats()
                           .withFormats(CONSOLE, TXT, HTML, XML));
    }

    @Override
    protected List<String> storyPaths() {
        // Specify story paths as remote URLs
        String codeLocation = codeLocationFromURL("http://jbehave.org/reference/examples/stories/")
                .toExternalForm();
        return asList(codeLocation + "and_step.story");
    }

}
]]>
</script>

<h2>Ignoring failures in stories</h2>

<p>By default, the story runners are configured to <b>fail-fast</b>,
i.e. the execution will stop at first failed story (but will complete
execution of the all the scenarios in the story first). To allow the
generation of a complete stories view (reporting how many stories
failed), the runners need to be enabled to run stories with <b>ignoreFailureInStories</b>
flag set to <b>true</b>. In this way, all stories will run and the
failure will be assessed only during the view generation. If any stories
failed, the build will fail correspondingly. Should the need to ignore
failure in the view arise (although generally not recommended), one can
set the <b>ignoreFailureInView</b> flag to <b>true</b>.</p>

<div class="clear">
<hr />
</div>

</body>
</html>
